Skip to content

chain: rescan on the client for btcd backends - #1515

Open
eynhaender wants to merge 2 commits into
btcsuite:masterfrom
eynhaender:fix/btcd-client-side-rescan
Open

eynhaender wants to merge 2 commits into
btcsuite:masterfrom
eynhaender:fix/btcd-client-side-rescan

Conversation

@eynhaender

@eynhaender eynhaender commented Nov 15, 2026 •

Copy link
Copy Markdown

Summary

RPCClient.Rescan used the btcd rescan command, which rpcclient marks as deprecated in favor of rescanblocks. The rescan now runs on the client, so btcd-compatible servers without rescan, such as libbitcoin-server, can serve as a chain backend, including for lnd's btcd backend.

Related: lightningnetwork/lnd#11583 removes lnd's own use of rescan in the btcd chain notifier.

Change Description

  1. The start block must be in the main chain.
  2. loadtxfilter loads the addresses and outpoints.
  3. getheaders walks the main chain from the start block in batches of 2000 headers. A batch that does not link to the last scanned block fails the rescan with ErrRescanReorg.
  4. rescanblocks matches each batch. Matches are delivered as relevant transactions, followed by a progress notification per batch.
  5. At the best block, the addresses and unspent outpoints, including outputs found by the scan, are registered with notifyreceived and notifyspent. Blocks connected in the meantime are scanned before the rescan finishes.

As with rescan, the start block is included. A rescan without addresses or outpoints finishes at the best block without scanning.

TestRPCClientRescanReorgServer runs the rescan against a btcd harness miner and changes the chain before a chosen call of the rescan: the start block, rescanned blocks or a fetched batch reorganized, a reorganization ahead of the scan, the last block reorganized or new blocks at the best block. The rescan must either finish with each main chain payment notified once, in its block, or fail without notifying a transaction outside its block.

Steps to Test

go test -race ./chain/ -run TestRPCClientRescan

Notes

  • A failed rescan is not retried. As with rescan, the wallet's rescan handler keeps the failed batch; this PR does not change that.
  • The lnd itest suite (btcd backend, 384 cases) with this change on v0.18.1 and chainntnfs/btcdnotify: scan the chain for historical spends lightningnetwork/lnd#11583 is identical to lnd master: 545 passed, 9 skipped. No rescan is sent, and all 1372 wallet rescans finish.
  • lnd v0.21.6 with this change syncs against a libbitcoin-server mainnet node, where the wallet never finished syncing before. A full rescan of 368,060 blocks for a 228-address wallet took 5m11s and found the same 397 transactions as a neutrino recovery of the same wallet.

RPCClient.Rescan issued the btcd rescan command, which rpcclient marks
as deprecated in favor of rescanblocks. Perform the rescan on the
client instead: load the addresses and outpoints with loadtxfilter,
walk the main chain from the start block with getheaders, and match
each batch of blocks with rescanblocks.

As with the rescan command, the start block is included and matching
transactions are delivered as relevant transactions. A progress
notification follows each batch. At the best block, the addresses and
the unspent outpoints, including outputs found by the scan, are
registered with notifyreceived and notifyspent, and blocks connected in
the meantime are scanned before the rescan finishes. A start block
outside the main chain, or a batch that does not link to the last
scanned block, fails the rescan.

This allows btcd-compatible servers that do not implement the
deprecated rescan command, such as libbitcoin-server, to serve as a
chain backend.
Add TestRPCClientRescanReorgServer, which runs the client-side rescan
against a btcd miner and changes the chain before a chosen call of the
rescan: invalidateblock followed by a fork with more work, or new blocks.
Each case builds about 2600 blocks above the best block with three
payments to the watched address, so that the rescan takes two getheaders
batches.

A rescan either finishes at the best block and notifies each payment
mined in the main chain once, in its block, or fails. Transactions
notified before a failure must be in the blocks they were notified in.

The cases cover a reorganization of the start block before the first
scan, of rescanned blocks, of a fetched batch before its scan, ahead of
the rescanned blocks, and of the last block at the best block, and new
blocks at the best block.

With RESCAN_REORG_SERVER the rescan runs against another btcd-compatible
server instead, which follows the miner over p2p.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant